home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / share / perl5 / Desktop / Notify.pm
Encoding:
Perl POD Document  |  2009-12-24  |  5.0 KB  |  218 lines
  1. package Desktop::Notify;
  2.  
  3. use warnings;
  4. use strict;
  5.  
  6. use Net::DBus;
  7. use File::Basename;
  8. use Data::Dumper;
  9.  
  10. use Desktop::Notify::Notification;
  11.  
  12. =head1 NAME
  13.  
  14. Desktop::Notify - Communicate with the Desktop Notifications framework
  15.  
  16. =head1 VERSION
  17.  
  18. Version 0.03
  19.  
  20. =cut
  21.  
  22. our $VERSION = '0.03';
  23.  
  24. =head1 SYNOPSIS
  25.  
  26.     use Desktop::Notify;
  27.     
  28.     # Open a connection to the notification daemon
  29.     my $notify = Desktop::Notify->new();
  30.     
  31.     # Create a notification to display
  32.     my $notification = $notify->create(summary => 'Desktop::Notify',
  33.                                        body => 'Hello, world!',
  34.                                        timeout => 5000);
  35.     
  36.     # Display the notification
  37.     $notification->show();
  38.     
  39.     # Close the notification later
  40.     $notification->close();
  41.  
  42. =head1 DESCRIPTION
  43.  
  44. This module provides a Perl interface to the Desktop Notifications framework.
  45.  
  46. The framework allows applications to display pop-up notifications on an X
  47. desktop.  This is implemented with two components: a daemon that displays the
  48. notifications, and a client library used by applications to send notifications
  49. to the daemon.  These components communicate through the DBus message bus
  50. protocol.
  51.  
  52. More information is available from
  53. L<http://trac.galago-project.org/wiki/DesktopNotifications>
  54.  
  55. This module serves the same purpose as C<libnotify>, in an object-oriented Perl
  56. interface.  It is not, however, an interface to C<libnotify> itself, but a
  57. separate implementation of the specification using L<Net::DBus>.
  58.  
  59. =head1 METHODS
  60.  
  61. =head2 new %opts
  62.  
  63. Connect to the notification daemon. %opts can include the following options:
  64.  
  65. =over
  66.  
  67. =item app_name
  68.  
  69. The application name to use for notifications. Default is C<basename($0)>
  70.  
  71. =item bus
  72.  
  73. The Net::DBus mesage bus to use. Default is to call Net::DBus->session, which
  74. is usually where notification-daemon can be reached.
  75.  
  76. =item service
  77.  
  78. The DBus service name of the daemon. Default is
  79. I<org.freedesktop.Notifications>.
  80.  
  81. =item objpath
  82.  
  83. The path to the notifications DBus object. Default is
  84. I</org/freedesktop/Notifications>.
  85.  
  86. =item objiface
  87.  
  88. The DBus interface to access the notifications object as. Default is
  89. I<org.freedesktop.Notifications>.
  90.  
  91. =back
  92.  
  93. =cut
  94.  
  95. sub new {
  96.     my ($class, %opts) = @_;
  97.  
  98.     my $self = {};
  99.  
  100.     $self->{bus} = $opts{bus} || Net::DBus->session;
  101.     $self->{service} = $self->{bus}
  102.         ->get_service($opts{service} || 'org.freedesktop.Notifications');
  103.     $self->{notify} = $self->{service}
  104.         ->get_object($opts{objpath} || '/org/freedesktop/Notifications',
  105.                      $opts{objiface} || 'org.freedesktop.Notifications');
  106.     $self->{app_name} = $opts{app_name} || basename($0);
  107.     $self->{notify}->connect_to_signal('NotificationClosed',
  108.                                        sub {$self->_close_cb(@_)});
  109.  
  110.     bless $self, $class;
  111. }
  112.  
  113. =head2 create %params
  114.  
  115. Creates a new notification object that can be displayed later. This will return
  116. a L<Desktop::Notify::Notification> object; see that module for information
  117. about using it.
  118.  
  119. =cut
  120.  
  121. sub create {
  122.     my ($self, %params) = @_;
  123.  
  124.     return new Desktop::Notify::Notification($self, %params);
  125. }
  126.  
  127. sub _register_notification {
  128.     my ($self, $n) = @_;
  129.     $self->{notes}->{$n->{id}} = $n;
  130. }
  131.  
  132. sub _close_cb {
  133.     my ($self, $nid) = @_;
  134.     print __PACKAGE__, ": notification closed\n";
  135.     if ($self->{close_callback})
  136.     {
  137.         print "invoking callback\n";
  138.         $self->{close_callback}->($self->{notes}->{$nid});
  139.     }
  140.     delete $self->{notes}->{$nid};
  141. }
  142.  
  143. =head2 close_callback $coderef
  144.  
  145. Sets a user-specified function to be called whenever a notification is closed.
  146. It will be called with one argument, which is the Notification object that was
  147. just closed.
  148.  
  149. =cut
  150.  
  151. sub close_callback {
  152.     my ($self, $cb) = @_;
  153.  
  154.     print "callback is $cb\n";
  155.     $self->{close_callback} = $cb;
  156. }
  157.  
  158. =head1 AUTHOR
  159.  
  160. Stephen Cavilia, C<< <sac at atomicradi.us> >>
  161.  
  162. =head1 SEE ALSO
  163.  
  164. L<Net::DBus>
  165.  
  166. L<http://www.galago-project.org/specs/notification/index.php>
  167.  
  168. L<http://www.galago-project.org/downloads.php>
  169.  
  170. =head1 BUGS
  171.  
  172. Please report any bugs or feature requests to
  173. C<bug-desktop-notify at rt.cpan.org>, or through the web interface at
  174. L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Desktop-Notify>.
  175. I will be notified, and then you'll automatically be notified of progress on
  176. your bug as I make changes.
  177.  
  178. =head1 SUPPORT
  179.  
  180. You can find documentation for this module with the perldoc command.
  181.  
  182.     perldoc Desktop::Notify
  183.  
  184. You can also look for information at:
  185.  
  186. =over 4
  187.  
  188. =item * AnnoCPAN: Annotated CPAN documentation
  189.  
  190. L<http://annocpan.org/dist/Desktop-Notify>
  191.  
  192. =item * CPAN Ratings
  193.  
  194. L<http://cpanratings.perl.org/d/Desktop-Notify>
  195.  
  196. =item * RT: CPAN's request tracker
  197.  
  198. L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Desktop-Notify>
  199.  
  200. =item * Search CPAN
  201.  
  202. L<http://search.cpan.org/dist/Desktop-Notify>
  203.  
  204. =back
  205.  
  206. =head1 ACKNOWLEDGEMENTS
  207.  
  208. =head1 COPYRIGHT & LICENSE
  209.  
  210. Copyright 2007 Stephen Cavilia, all rights reserved.
  211.  
  212. This program is free software; you can redistribute it and/or modify it
  213. under the same terms as Perl itself.
  214.  
  215. =cut
  216.  
  217. 1; # End of Desktop::Notify
  218.